home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / memchek.exe / MEMWATCH.TXT < prev   
Text File  |  1991-10-03  |  5KB  |  137 lines
  1.             MEMCHECK Version 1.0
  2.  
  3.  The Memcheck library contains various functions to help monitor heap
  4.  usage and heap consistency in a real time mode for programs written in
  5.  Microsoft C.
  6.  
  7.  To make these functions active you must code a call to the MemWatch
  8.  function from within your program.
  9.   
  10.   Usage:
  11.    
  12.    void  MemWatch(n);
  13.  
  14.    int n;
  15.  
  16.    This function call installs the heap routines and optionally causes a
  17.    _heapchk( ) call to be invoked every n clock ticks. A value of -1 
  18.    causes only the heap routines to be installed and not the periodic
  19.    checking of the heap.
  20.  
  21.    Pressing right shift F1 will display the memcheck menu. Currently this
  22.    will display as follows:
  23.  
  24.      (W)alk Heap
  25.          (H)eap Statistics
  26.          (R)eset Heap
  27.  
  28.      Heap status is : HEAPOK
  29.        
  30.  
  31.    the line showing the heap status can have the following values :
  32.  
  33.    HEAPOK       : The heap is not corrupted
  34.    HEAPBADBEGIN : The start of heap ptr is missing or is invalid
  35.    HEAPBADNODE  : The heap is damaged
  36.     
  37.    any value other than HEAPOK means that your program has probably 'stamped'
  38.    on memory somewhere.
  39.  
  40.    Walk Heap.
  41.  
  42.    This option allows you to walk through each entry in the heap. the display
  43.    gives you the address of the block of memory, the size of the block of memory
  44.    and whether it is in use or is free. If a block is in use then you should have
  45.    in your program a char *ptr that equals the heap data address. A free block is
  46.    the result of doing a free(ptr) call. This display also shows you the contents
  47.    of this heap block. Presiing PGDN and PGUP allows you to scroll through this
  48.    memory. Pressing 'N' or 'P' allows you to move through the heap.
  49.  
  50.    Heap Statistics.
  51.    
  52.    This option gives you a snapshot of how your program is utilising memory. It
  53.    displays the following information:
  54.  
  55.    Used Blocks            - The number of heap entrys that are flagged as being
  56.                             in use; i.e they are assigned to ptrs that have been
  57.                             malloc( ) but not free( );
  58.    Free Blocks            - The number of heap entrys that were malloc( ) then
  59.                             free( ) but have not been reused.
  60.  
  61.    The address and size of the largest used block of memory.
  62.    
  63.    The address and size of the largest free block of memory.
  64.  
  65.    The amount of memory available to your program. This number is the
  66.    value returned by _memavl( );
  67.   
  68.    Reset Probe.
  69.     
  70.    This option allows you to modify how often the _heapchk( ) function is
  71.    called. The number entered is the number of clock ticks that must pass
  72.    before a call to _heapchk( ) is made. An entry of 0 disables this call.
  73.    Approximately 18.2 clock ticks occur a second so an entry of 50 will cause
  74.    the _heapchk( ) routine to be invoked nearly every 3 seconds. If the
  75.    return from _heapchk( ) is bad then the memcheck menu, described above,
  76.    will automatically appear with the relevant heap error message displayed.
  77.  
  78.    WARNING:
  79.  
  80.    It can happen that the _heapchk( ) call is made while your program is in
  81.    the middle of a malloc( ) or free( ). Because some internal reorganisation
  82.    of the heap is taking place the _heapchk( ) function will give a bad return 
  83.    causing the memcheck menu to be displayed.
  84.   
  85.   To disable all these functions code the following function call:
  86.   
  87.      MemCancel( );
  88.  
  89.   After this function call shift-f1 will no longer display the memcheck
  90.   menu and the heap probe will be disabled. 
  91.  
  92.   I wrote these functions to enable me to discover how malloc( ) and free( )
  93.   worked. They don't work the way you think they would in terms of reusing
  94.   blocks of memory etc.
  95.   This Library has been tested using Microsoft C version 5.1 and 6.0. I have
  96.   no idea if it will work with any other C compiler.
  97.   This library only works with large model C programs and on 286 or better
  98.   Machines. If you would like librarys for other memory models or 8088
  99.   processors please contact me at the address below ot via CIS 71507,1033.
  100.  
  101.   Steve Bridges
  102.   1391 Union street
  103.   Manchester NH 03104
  104.  
  105.   As usual you use these functions at your own risk. 
  106.  
  107.   Example Program:
  108.   below is an example of how to incorporate the functions in this
  109.   library and how to compile and link your application:
  110.  
  111.   void Memwatch(int);                   // function prototype
  112.   
  113.   main( )
  114.   {
  115.  
  116.    MemWatch(20);            // link in the routines with a call to
  117.                             // _heapcheck every 20 clock ticks (about
  118.                             // every 1.1 seconds)      
  119.  
  120.   ......                   // do some stuff
  121.  
  122.   MemCancel( );            // disables the routines. 
  123.   }
  124.  
  125.   Compile.
  126.  
  127.    cl /c /AL /G2  xxxxx.c
  128.  
  129.   Link.
  130.  
  131.   link xxxxx,,,memcheck;
  132.  
  133.  
  134.  
  135.  
  136.  
  137.